<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>jQuery Mobile Docs - Popup</title>
	<link rel="stylesheet"  href="../../../css/themes/default/jquery.mobile-1.2.0.css" />
	<link rel="stylesheet" href="../../_assets/css/jqm-docs.css"/>

	<script src="../../../js/jquery.js"></script>
	<script src="../../../docs/_assets/js/jqm-docs.js"></script>
	<script src="../../../js/jquery.mobile-1.2.0.js"></script>
	
</head>
<body>

	<div data-role="page" class="type-interior">

		<div data-role="header" data-theme="f" data-position="fixed">
		<h1>Popup</h1>
		<a href="../../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
		<a href="../../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
	</div><!-- /header -->

	<div data-role="content" class="ui-body">
		<div class="content-primary">

			<h2>Popup</h2>

			<ul data-role="controlgroup" data-type="horizontal" class="localnav">
				<li><a href="index.html" data-role="button" data-transition="fade" class="ui-btn-active">Basics</a></li>
				<li><a href="options.html" data-role="button" data-transition="fade">Options</a></li>
				<li><a href="methods.html" data-role="button" data-transition="fade">Methods</a></li>
				<li><a href="events.html" data-role="button" data-transition="fade">Events</a></li>
			</ul>

			<p>To create a popup, add the <code>data-role="popup"</code> attribute to a div with the popup contents. Then create a link with the <code>href</code> set to the <code>id</code> of the popup div, and add the attribute <code>data-rel="popup"</code> to tell the framework to open the popup when the link is tapped. This is a similar markup pattern to the <a href="../dialog/index.html">dialog</a> widget. A popup div has to be nested inside the same page as the link.</p>

<pre><code>
&lt;a href=&quot;#popupBasic&quot; <strong>data-rel=&quot;popup&quot;</strong>&gt;Open Popup&lt;/a&gt;

&lt;div <strong>data-role=&quot;popup&quot;</strong> id=&quot;popupBasic&quot;&gt;
	&lt;p&gt;This is a completely basic popup, no options set.&lt;p&gt;
&lt;/div&gt;
</code></pre>

		<p>This will result in the following popup:</p>
		<a href="#popupBasic" data-rel="popup" data-role="button" data-inline="true">Open Popup</a>
		
		<div data-role="popup" id="popupBasic">
			<p>This is a completely basic popup, no options set.</p>
		</div>

		<p>The popup consists of two elements: the screen, which is a transparent or translucent element that covers the entire document, and the container, which is the popup itself. If your original element had an <code>id</code> attribute, the screen and the container will each receive an <code>id</code> attribute based on it. The screen's <code>id</code> will be suffixed with "-screen", and the container's <code>id</code> will be suffixed with "-popup" (in the above example, <code>id="popupBasic-screen"</code> and <code>id="popupBasic-popup"</code>, respectively).</p>
		
		<p>The framework adds a small amount of margin to text elements, but it's really just a container with <strong>rounded corners</strong> and a <strong>shadow</strong> which serves as a blank slate for your designs (even these features can be disabled via <a href="options.html">options</a>).</p>

		<p>This simple styling makes it easy to add in widgets to create a variety of different interactions. Here are a few real-world examples that combine the various settings and styles you can achieve out of the box with popups:</p>
		
		<a href="#popupInfo" data-rel="popup" data-role="button" data-inline="true">Tooltip</a>
		<a href="#popupMenu" data-rel="popup" data-role="button" data-inline="true">Menu</a>
		<a href="#popupNested" data-rel="popup" data-role="button" data-inline="true">Nested menu</a>
		<a href="#popupLogin" data-rel="popup" data-position-to="window" data-role="button" data-inline="true">Form</a>
		<a href="#popupDialog" data-rel="popup" data-position-to="window" data-role="button" data-inline="true" data-transition="pop">Dialog</a>
		<a href="#popupPhoto" data-rel="popup" data-position-to="window" data-role="button" data-inline="true" data-transition="fade">Photo</a>
		
		<div data-role="popup" id="popupInfo" class="ui-content" data-theme="e" style="max-width:350px;">
          <p>Here is a <strong>tiny popup</strong> being used like a tooltip. The text will wrap to multiple lines as needed.</p>
		</div>

		<div data-role="popup" id="popupMenu" data-theme="a">
				<ul data-role="listview" data-inset="true" style="min-width:210px;" data-theme="b">
					<li data-role="divider" data-theme="a">Popup API</li>
					<li><a href="options.html">Options</a></li>
					<li><a href="methods.html">Methods</a></li>
					<li><a href="events.html">Events</a></li>
				</ul>
		</div>


		<div data-role="popup" id="popupNested" data-theme="none">
			<div data-role="collapsible-set" data-theme="b" data-content-theme="c" data-collapsed-icon="arrow-r" data-expanded-icon="arrow-d" style="margin:0; width:250px;">
				<div data-role="collapsible" data-inset="false">
					<h2>Farm animals</h2>
					<ul data-role="listview">
						<li><a href="../dialog.html" data-rel="dialog">Chicken</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Cow</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Duck</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Sheep</a></li>
					</ul>
				</div><!-- /collapsible -->
				<div data-role="collapsible" data-inset="false">
					<h2>Pets</h2>
					<ul data-role="listview">
						<li><a href="../dialog.html" data-rel="dialog">Cat</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Dog</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Iguana</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Mouse</a></li>
					</ul>
				</div><!-- /collapsible -->
				<div data-role="collapsible" data-inset="false">
					<h2>Ocean Creatures</h2>
					<ul data-role="listview">
						<li><a href="../dialog.html" data-rel="dialog">Fish</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Octopus</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Shark</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Starfish</a></li>
					</ul>
				</div><!-- /collapsible -->
				<div data-role="collapsible" data-inset="false">
					<h2>Wild Animals</h2>
					<ul data-role="listview">
						<li><a href="../dialog.html" data-rel="dialog">Lion</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Monkey</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Tiger</a></li>
						<li><a href="../dialog.html" data-rel="dialog">Zebra</a></li>
					</ul>
				</div><!-- /collapsible -->
			</div><!-- /collapsible set -->
		</div><!-- /popup -->
		

		<div data-role="popup" id="popupLogin" data-theme="a" class="ui-corner-all">
			<form>
				<div style="padding:10px 20px;">
				  <h3>Please sign in</h3>
		          <label for="un" class="ui-hidden-accessible">Username:</label>
		          <input type="text" name="user" id="un" value="" placeholder="username" data-theme="a" />

		          <label for="pw" class="ui-hidden-accessible">Password:</label>
		          <input type="password" name="pass" id="pw" value="" placeholder="password" data-theme="a" />

		    	  <button type="submit" data-theme="b">Sign in</button>
				</div>
			</form>
		</div>
		
		<div data-role="popup" id="popupDialog" data-overlay-theme="a" data-theme="c" style="max-width:400px;" class="ui-corner-all">
			<div data-role="header" data-theme="a" class="ui-corner-top">
				<h1>Delete Page?</h1>
			</div>
			<div data-role="content" data-theme="d" class="ui-corner-bottom ui-content">
				<h3 class="ui-title">Are you sure you want to delete this page?</h3>
				<p>This action cannot be undone.</p>
				<a href="#" data-role="button" data-inline="true" data-rel="back" data-theme="c">Cancel</a>    
				<a href="#" data-role="button" data-inline="true" data-rel="back" data-transition="flow" data-theme="b">Delete</a>  
			</div>
		</div>

		<div data-role="popup" id="popupPhoto" data-overlay-theme="a" data-theme="d" data-corners="false">
			<a href="#" data-rel="back" data-role="button" data-theme="a" data-icon="delete" data-iconpos="notext" class="ui-btn-right">Close</a><img class="popphoto" src="../../_assets/images/colorful-city.jpg" alt="Colorful city">
		</div>
			
		<h3>Advanced popup techniques</h3>
		<p>Learn how to customize and extend popups by working with the API, custom scripts, and styles.</p>
		<a href="popup-images.html" data-ajax="false" data-role="button" data-inline="true" data-icon="arrow-r" data-iconpos="right">Scaling images</a>
		<a href="popup-iframes.html" data-ajax="false" data-role="button" data-inline="true" data-icon="arrow-r" data-iconpos="right">Map + video iframes</a>
		<a href="popup-panels.html" data-ajax="false" data-role="button" data-inline="true" data-icon="arrow-r" data-iconpos="right">Overlay panels</a>
		
		<h2>Calling the popup plugin</h2>

		<p>This plugin will autoinitialize on any page that contains a div with the attribute <code>data-role="popup"</code>. However, if needed you can directly call the <code>popup</code> plugin on any selector, just like any jQuery plugin and programmatically work with the popup <a href="options.html">options</a>, <a href="methods.html">methods</a>, and <a href="events.html">events</a> API:</p>
		
<pre><code>
$( "#myPopupDiv" ).popup();
</code></pre>

		<h2>Opening popups</h2>
		
		<p>Using the markup-based configuration, when a link with the <code>data-rel="popup"</code> is tapped, the corresponding popup container with the id referenced in the <code>href</code> of the link will be shown. To open a popup programmatically, call popup with the <code>open</code> method on the popup container:</p>
		
<pre><code>
$( "#myPopupDiv" ).popup( "open" )
</code></pre>

		<h2>Closing popups</h2>
		<p>Popups can be closed either by clicking outside the popup widget or by pressing the <code>Esc</code> key. Popups can also be closed via the <code>close</code> method:</p>
			
<pre><code>
$( "#myPopupDiv" ).popup( "close" )
</code></pre>
			
			<p>To add an explicit close button to a popup, add a link with the role of button into the popup container with a <code>data-rel="back"</code> attribute which will close the popup when tapped. We have created helper classes to position buttons in the upper left (<code>ui-btn-left</code>) or upper right (<code>ui-btn-right</code>) of the popup but you may need to tweak these or add custom positioning styles depending on your design. We recommend adding standard content padding to the popup to make room for the buttons (see next section).</p>
		
		
		<pre><code>
&lt;div data-role=&quot;popup&quot;&gt;
	<strong>&lt;a href=&quot;#&quot; data-rel=&quot;back&quot; data-role=&quot;button&quot; data-theme=&quot;a&quot; data-icon=&quot;delete&quot; data-iconpos=&quot;notext&quot; class=&quot;ui-btn-right&quot;&gt;Close&lt;/a&gt;</strong>
	...popup contents go here...
&lt;/div&gt;
		</code></pre>
				
		<a href="#popupCloseRight" data-rel="popup" data-role="button" data-inline="true">Popup with close button right</a>
		<a href="#popupCloseLeft" data-rel="popup" data-role="button" data-inline="true">Popup with close button left</a>
		
		<div data-role="popup" id="popupCloseRight" class="ui-content" style="max-width:280px">
			<a href="#" data-rel="back" data-role="button" data-theme="a" data-icon="delete" data-iconpos="notext" class="ui-btn-right">Close</a>
			<p>I have a close button at the top right corner with simple HTML markup.</p>
		</div>
		
		<div data-role="popup" id="popupCloseLeft" class="ui-content" style="max-width:280px">
			<a href="#" data-rel="back" data-role="button" data-theme="a" data-icon="delete" data-iconpos="notext" class="ui-btn-left">Close</a>
			<p>I have a close button at the top left corner with simple HTML markup.</p>
		</div>
		
		<h2>Adding padding</h2>
		<p>For popups with formatted text, padding is needed. We recommend adding the <code>ui-content</code> class to the popup container which adds the standard 15px of padding, just like the page content container. Write your own styles to create a more customized design if needed.</p>
		
		<pre><code>
&lt;a href=&quot;#popupPadded&quot; data-rel=&quot;popup&quot; data-role=&quot;button&quot;&gt;Popup with padding&lt;/a&gt;

&lt;div data-role=&quot;popup&quot; id=&quot;popupPadded&quot; <strong>class=&quot;ui-content&quot;</strong>&gt;
	&lt;p&gt;This is a popup with the &lt;code&gt;ui-content&lt;/code&gt; class added to the popup container.&lt;/p&gt;
&lt;/div&gt;
		</code></pre>
		
		<p>This will result in the following popup with content padding:</p>
		<a href="#popupPadded" data-rel="popup" data-role="button" data-inline="true">Popup with padding</a>
		
		<div data-role="popup" id="popupPadded" class="ui-content">
			<p>This is a popup with the <code>ui-content</code> class added to the popup container.</p>
		</div>
		
		<p>When padding is added, we apply a few style rules to negate the top margin for the first heading or paragraph in the popup and do the same for the last element's bottom margin. This keep the popups from having too much vertical space when the content padding and element margins combine.</p>
	
		
		<h2>Positioning options</h2>
		<p>By default, popups open centered vertically and horizontally over the thing you clicked (the origin) which is good for popups used as tooltips or menus. The framework also applies some basic collision detection rules to ensure that the popup will appear on-screen so the ultimate position may not always be centered over the origin.</p>
		<p>For situations like a dialog or lightbox where the popup should appear centered within the window instead of over the origin, add the <code>data-position-to</code> attribute to the <strong>link</strong> and specilf a value of <code>window</code>. </p>	
		<p>It's also possible to specilf any valid selector as the value of <code>position-to</code> in addition to <code>origin</code> and <code>window</code>. For example, if you add <code>data-position-to="#myElement"</code> the popup will be positioned over the element with the id <code>myElement</code>.</p>	
<pre id="codeSample"><code>
&lt;a href=&quot;#positionWindow&quot; data-rel=&quot;popup&quot; <strong>data-position-to=&quot;window&quot;</strong>&gt;

&lt;div data-role=&quot;popup&quot; id=&quot;positionWindow&quot;&gt;
	&lt;p&gt;I am positioned to the window.&lt;/p&gt;
&lt;/div&gt;
</code></pre>

		<p>A few examples:</p>

		<a href="#positionWindow" data-role="button" data-inline="true" data-rel="popup" data-position-to="window">Position to window</a> 
		<a href="#positionOrigin" data-role="button" data-inline="true" data-rel="popup" data-position-to="origin">Position to origin</a>
		<a href="#positionSelector" data-role="button" data-inline="true" data-rel="popup" data-position-to="#codeSample">Position to #codeSample</a>

		<div data-role="popup" id="positionWindow" class="ui-content" data-theme="d">
			<p>I am positioned to the window.</p>
		</div>

		<div data-role="popup" id="positionOrigin" class="ui-content" data-theme="d">
			<p>I am positioned over the origin.</p>
		</div>
		
		<div data-role="popup" id="positionSelector" class="ui-content" data-theme="d">
			<p>I am positioned over the code sample via selector.</p>
		</div>


		<p>The popup's placement constraints, which may cause the popup not to appear centered as desired, are as follow:</p>
		<ol>
			<li>The width of the popup will be limited using CSS <code>max-width</code> to the width of the window minus a tolerance of 15px on either side.</li>
			<li>A tolerance from the edges of the window (15px from each of the sides and 30px from the top and the bottom) will be observed when the popup fits inside the window. Tall popups are allowed to overflow the top and bottom edges of the window. Those parts of the popup can be viewed by manually scrolling the document. This tolerance is a <a href="options.html">configurable option</a>.</li>
			<li>The top coordinate of the popup will never be negative. This ensures that the top of the popup will not be cut off.</li>
			<li>If centering the popup over an element would cause the overall height of the document to increase, the popup is shifted upwards at most until its top coordinate becomes 0.</li>
		</ol>
        
        <p>Also note that a popup is currently always placed at the center of the window after an orientation change or window resize event.</p>

		<p>See <a href="methods.html">methods</a> for information about setting the popup position programmatically, including the option to specilf <strong>x and y coordinates</strong>.</p>

		<h2>Setting transitions</h2>
		<p>By default, popups have no transition to make them open as quickly as possible. To set the transition used for a popup, add the <code>data-transition</code> attribute to the link that references the popup. The reverse version of the transition will be used when closing the popup.</p>
				
<pre><code>
&lt;a href=&quot;#transitionExample&quot; <strong>data-transition=&quot;flip&quot;</strong> data-rel=&quot;popup&quot;&gt;
   Flip transition
&lt;/a&gt;
</code></pre>
				
		<p>For performance reasons on mobile devices, we recommend using simpler transitions like pop, fade or none for smooth and fast popup animations, especially with larger or complex widgets within a popup. To view all transition types, you must be on a browser that supports 3D transforms. By default, devices that lack 3D support (such as Android 2.x) will fallback to "fade" for all transition types. See the <a href="../page-transitions.html">transitions</a> page for detailed information on the transition system.</p>
				
		<a href="#transitionExample" data-transition="none" data-role="button" data-inline="true" data-rel="popup">No transition</a>
		<a href="#transitionExample" data-transition="pop" data-role="button" data-inline="true" data-rel="popup">Pop</a>
		<a href="#transitionExample" data-transition="fade" data-role="button" data-inline="true" data-rel="popup">Fade</a>
		<a href="#transitionExample" data-transition="flip" data-role="button" data-inline="true" data-rel="popup">Flip</a>
		<a href="#transitionExample" data-transition="turn" data-role="button" data-inline="true" data-rel="popup">Turn</a>
		<a href="#transitionExample" data-transition="flow" data-role="button" data-inline="true" data-rel="popup">Flow</a>
		<a href="#transitionExample" data-transition="slide" data-role="button" data-inline="true" data-rel="popup">Slide</a>
		<a href="#transitionExample" data-transition="slidefade" data-role="button" data-inline="true" data-rel="popup">Slidefade</a>
		<a href="#transitionExample" data-transition="slideup" data-role="button" data-inline="true" data-rel="popup">Slide up</a>
		<a href="#transitionExample" data-transition="slidedown" data-role="button" data-inline="true" data-rel="popup">Slide down</a>


		<div data-role="popup" id="transitionExample" class="ui-content" data-theme="d">
			<p>I'm a simple popup.</p>
		</div>
											
		<p>When you launch the popup from any of the buttons, the <code>data-transition</code> set on the button will be used. However, if you launch the popup programmatically, such as via <code>$( "#transitionExample" ).popup( "open" )</code>, the <code>data-transition</code> attribute specified in the definition of the popup will be used if present.</p>
		

		<h2>Theming the popup and overlay</h2>
		
		<p>The <code>popup</code> plugin provides two theme-related options: <code>data-theme</code> and <code>data-overlay-theme</code>. The <code>data-theme</code> option refers to the theme of the popup itself, whereas <code>data-overlay-theme</code> refers to the theme of the popup's background, which covers the entire window behind the popup.</p>
		<p><code>data-theme</code> will be inherited from the page, and will always have a valid value when the popup opens, unless you explicitly specilf <code>data-theme=&quot;none&quot;</code>, in which case the popup will have a transparent background.</p>
		<p>The <code>data-overlay-theme</code> will never be set, and the popup's background, although always present when the popup is shown, will be completely transparent, unless explicitly set using for example <code>data-overlay-theme=&quot;a&quot;</code>. In this case, the background will fade in, partially obscuring the rest of the window, to further direct attention to the popup. Here is an example of an explicitly themed popup:</p>

<pre><code>
&lt;div id=&quot;both&quot; data-role=&quot;popup&quot; <strong>data-theme=&quot;e&quot; data-overlay-theme=&quot;a&quot;</strong> class=&quot;ui-content&quot;&gt;
  ...Popup contents...
&lt;/div&gt;
</code></pre>

		<a href="#theme" data-rel="popup" data-role="button" data-inline="true">Theme A</a>
		<div id="theme" data-role="popup" data-theme="a" class="ui-content">
		  <p>I have <code>data-theme="a"</code> set on me</p>
		</div>
		
		<a href="#transparent" data-rel="popup" data-role="button" data-inline="true">Theme "none", no shadow</a>
		<div id="transparent" data-role="popup" data-theme="none" data-shadow="false">
			<a href="#" data-rel="back" data-role="button" data-theme="a" data-icon="delete" data-iconpos="notext" class="ui-btn-right">Close</a>
		  <img src="../../_assets/images/firefox-logo.png" class="popphoto" alt="firefox logo on a transparent popup">
		</div>

		<a href="#overlay" data-rel="popup" data-role="button" data-inline="true">Overlay theme A</a>
		<div id="overlay" data-role="popup" data-overlay-theme="a" class="ui-content">
		  <p>I have a <code>data-overlay-theme="a"</code> set on me</p>
		</div>

		<a href="#both" data-rel="popup" data-role="button" data-inline="true">Theme E + overlay A</a>
		<div id="both" data-role="popup" data-overlay-theme="a" data-theme="e" class="ui-content">
		  <p>I have <code>data-theme="e"</code> and <code>data-overlay-theme="a"</code> set on me</p>
		</div>


		<h2>Note: Chaining of popups not allowed</h2>
		<p>The framework does not currently support chaining of popups so it's not possible to embed a link from one popup to another popup. All links with a <code>data-rel="popup"</code> inside a popup will not do anything at all.</p>
		<p>This also means that custom select menus will not work inside popups, because they are themselves implemented using popups. If you place a select menu inside a popup, it will be rendered as a native select menu, even if you specilf <code>data-native-menu="false"</code>.</p>
		<p>A workaround to get chained popups working is the use of a timeout for example in the <code>popupafterclose</code> event bound to the invoking popup. In the following example, when the first popup is closed, the second will be opened by a delayed call to the <code>open</code> method:</p>
<pre><code>
$( document ).on( "pageinit", function() {
    $( '.popupParent' ).on({
        popupafterclose: function() {
            setTimeout( function(){ $( '.popupChild' ).popup( 'open' ) }, 100 );
        }
    });
});
</code></pre>


	</div><!--/content-primary -->

				<div class="content-secondary">

					<div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">

							<h3>More in this section</h3>

							<ul data-role="listview" data-theme="c" data-dividertheme="d">

								<li data-role="list-divider">Pages &amp; Dialogs</li>
								<li><a href="../page-anatomy.html">Anatomy of a page</a></li>
								<li><a href="../page-template.html" data-ajax="false">Single page template</a></li>
								<li><a href="../multipage-template.html" data-ajax="false">Multi-page template</a></li>
								<li><a href="../page-titles.html">Page titles</a></li>
								<li><a href="../page-links.html">Linking pages</a></li>
								<li><a href="../page-transitions.html" data-ajax="false">Page transitions</a></li>
								<li><a href="../loader.html">Page loading widget</a></li>
								<li><a href="../dialog/index.html">Dialogs</a></li>
								<li data-theme="a"><a href="index.html">Popups</a></li>
								<li><a href="../page-cache.html">Prefetching &amp; caching pages</a></li>
								<li><a href="../page-navmodel.html">Ajax, hashes &amp; history</a></li>
								<li><a href="../page-dynamic.html">Dynamically Injecting Pages</a></li>
								<li><a href="../page-scripting.html">Scripting pages</a></li>
								<li><a href="../phonegap.html">PhoneGap apps</a></li>
								<li><a href="../touchoverflow.html">touchOverflow feature</a></li>
								<li><a href="../pages-themes.html">Theming pages</a></li>

							</ul>
					</div>
				</div>

</div><!-- /content -->

<div data-role="footer" class="footer-docs" data-theme="c">
		<p class="jqm-version"></p>
		<p>&copy; 2012 jQuery Foundation and other contributors</p>
</div>

</div><!-- /page -->

</body>
</html>
